6

Tagging Content

XML lets you tag, or label, the content of documents. Tagging lets you label the various parts of documents. This in turn enables you to use that tagged content in a wide variety of ways, including on the World Wide Web.

Avenue.quark gives you a unique means of tagging text and pictures in QuarkXPress documents. You can tag elements manually or use tagging rule sets to automate part of the tagging process.

Avenue.quark lets you create and open XML documents from the File menu. You can save XML documents using buttons on the XML Workspace palette.

To create a new XML document:

1. Choose File > New > XML, or press Command+Shift+X (Mac OS) or Ctrl+Shift+X (Windows). The New XML dialog box is displayed.

The New XML dialog box lets you create a new XML document.

2. To base the new XML document on an XML template, select an item in the Template list. To create a new XML document that is not based on a template, click Import in the DOCTYPE area, select a DTD, and then choose a root element from the Root Element pop-up menu.

For more information about XML templates, see "Working with XML Templates" in this chapter.

3. If you are basing the new XML document on a template and you plan to use rule-based tagging, choose a default tagging rule set from the Default Set pop-up menu.

4. Click OK. The new XML document is displayed in a new XML Workspace palette.

Once you complete this step, the DTD and root element of the XML document cannot be changed.

By default, a new XML document contains only those elements that are mandatory at the root level according to the DTD, plus any mandatory children of those elements. If the DTD requires one of a list of non-optional elements (for example, (a | b | c)), avenue.quark uses the first element in the list (here, a). If the DTD requires one of a list of elements, and one or more of those elements is optional (for example, (a | b | c?)), avenue.quark leaves the parent element empty.

Avenue.quark creates only valid XML documents (that is, documents that adhere to their DOCTYPE).

If you want to create a new document based on an XML template file that's not in the "Templates" file inside your QuarkXPress folder, just choose File > Open and open the XML template file that way.

Avenue.quark lets you open XML documents created by avenue.quark or any other valid XML document that includes its DTD or references an available DTD. To open an XML document in avenue.quark:

1. Choose File > Open (Command+O on Mac OS, Ctrl+O on Windows).

2. Windows only: Choose XML (*.xml) from the Files of type pop-up menu.

3. Use the controls in the dialog box to locate the document you want to open; then highlight the document in the list.

Avenue.quark can open only XML documents that have a file name suffix of ".xml".

4. Click Open.

5. If the XML file was generated by avenue.quark, avenue.quark attempts to open the QuarkXPress document that most recently contributed content to it. If avenue.quark cannot find the QuarkXPress document, a dialog box is displayed, asking you to locate it; either select the QuarkXPress file and click Open, or click Cancel. (The XML file will still open if you click Cancel.)

If an "XML document error" message is displayed, this means the document you are opening contains an error. "XML document error" is followed by the error type, and then the line number and column number (in that order) of the character where the error occurred.

6. If the QuarkXPress document is available, avenue.quark compares the content in the document to the corresponding content in the XML document and notifies you of any differences.

Avenue.quark supports the UTF-8, UTF-16 (Unicode), and Shift-JIS encodings, and automatically adds an encoding specification when you save an XML file. If an XML file does not have an encoding specification, avenue.quark assumes its encoding to be UTF-8. For more information about encodings, see Appendix C, "Understanding Encodings," in Chapter 7, "Appendices."

Buttons on the XML Workspace palette lets you save XML documents under their current names or under a new name.

From left to right: the Save, Save As, and Revert to Saved buttons.

• To save the active XML document under its current name, click the Save button.
• To save the active XML document under a new name, click the Save As button. The Save As dialog box is displayed. Name the XML file; choose a type from the Type pop-up menu; choose an encoding method from the Encoding pop-up menu; check or uncheck Save XML as Standalone; and then click Save.

The Save as dialog box lets you name an XML file, specify whether to save the file as an XML document or avenue.quark template, and specify an encoding method.

• To revert to the last-saved version of the active XML document, click the Revert to Saved button.

When you save an XML document in avenue.quark, a number of things happen:

• If Save XML as Standalone is checked, avenue.quark adds a copy of the DTD to the file's internal subset, so the file can be opened and validated on computers where the DTD is unavailable. (If Save XML as Standalone is unchecked, the appropriate DTD must be available in order for avenue.quark to open the XML file.)
• Avenue.quark adds several processing instructions to the file, indicating the name of the QuarkXPress document (if any) that most recently contributed content to the document and the location of that content in the QuarkXPress document.
• If the XML document contains an empty ID attribute for which a value is required, a dialog box is displayed. At that point, you can complete the save (resulting in an invalid XML document), or abandon the save and view the empty attribute in the XML Workspace palette.
• If the XML document contains an ID attribute with the same value as another ID attribute in the same document, a dialog box is displayed. At that point, you can complete the save (resulting in an invalid XML document), or abandon the save and view the duplicate attribute in the XML Workspace palette.
• If the XML document contains an empty IDREF attribute for which a value is required, a dialog box is displayed. At that point, you can complete the save (resulting in an invalid XML document), or abandon the save and view the empty attribute in the XML Workspace palette.
• If the XML document contains an IDREF attribute whose value does not match the value of any ID attribute in the active XML document, a dialog box is displayed. If the IDREF attribute value refers to an ID attribute value in an XML document referred to by the active XML document, you can complete the save. If not, you can abandon the save and view the problematic IDREF attribute in the XML Workspace palette.
• If the XML document contains empty CDATA attributes for which a value is required, an underscore (_) is inserted in those attributes.

An XML template is an avenue.quark XML document that contains a DTD, a root element specification, and an optional default tagging rule set. An XML template may also contain a "starter" set of elements, attributes, comments, processing instructions, PCDATA blocks, and content. The purpose of XML templates is to save users from having to repeat the same setup steps over and over again when creating a series of XML documents that are all based on the same DTD, root element, and tagging rule set.

To be available in avenue.quark, XML templates must be stored in the "Templates" folder, which is in the same folder as the QuarkXPress application. XML templates must have a file name suffix of ".xmt", even on Mac OS.

To create a new XML template:

1. Choose File > New > XML, or press Command+Shift+X (Mac OS) or Ctrl+Shift+X (Windows). The New XML dialog box is displayed.

2. If you want to base the template on another template, select that template's name in the Template list and then go to Step 4.

The New XML dialog box lets you create new XML templates.

3. If you want to create the template from scratch, select Custom in the Template list; click Import in the DOCTYPE area and select a DTD file; then choose a root element from the Root Element pop-up menu.

4. If you are basing the new template on an existing template and you plan to use rule-based tagging, choose a default tagging rule set from the Default Set pop-up menu.

5. Click OK. The new XML document is displayed in a new XML Workspace palette.

6. Add any elements, attributes, comments, processing instructions, PCDATA blocks, or content that you want the template to contain.

7. Click the Save As button. The Save as dialog box is displayed.

The Save as dialog box lets you name an XML file, specify whether to save the the file as an XML document or avenue.quark template, and specify an encoding method for the file.

8. Enter a name for the file in the Save Current XML as field. Keep in mind that XML templates must have a file name that ends in ".xmt", even on Mac OS.

9. Choose avenue.quark Template from the Type pop-up menu.

10. Choose an encoding method from the Encoding pop-up menu.

11. If you want the template to be available in the New XML dialog box, navigate to the "Templates" folder inside your QuarkXPress folder. (Templates that are not stored in the "Templates" folder can be opened by choosing File > Open.)

12. Click Save.

Templates are always saved as standalone documents because they must contain a DTD.

The XML Workspace palette's hierarchical XML Tree list makes it easy for you to view and work with the content of XML documents. A handy pop-up menu makes it easy for you to insert, delete, and replace elements, comments, PCDATA blocks, and processing instructions.

You can insert a new element, comment, PCDATA block, or processing instruction above, below, or as a child of the item selected in the XML Tree list (XML Workspace palette). You can also replace the selected item with a different item if the DTD permits it. To insert or replace an item in the active XML document:

1. In the XML Workspace palette, select an item in the XML Tree list.

2. Control+click (Mac OS) or right+click (Windows) the item to display the XML Tree pop-up menu, and then choose Insert Child, Insert Sibling Before, Insert Sibling After, or Replace. A submenu displays.

The submenu for the Insert Child, Insert Sibling Before, Insert Sibling After, and Replace commands lets you choose what kind of element to insert or substitute.

3. If you want to insert or substitute an element, comment, processing instruction, or PCDATA block without a preview, simply choose it from the submenu.

4. If you would like to see a preview before you insert or replace, choose Insert with Preview. The Insert with Preview dialog box is displayed.

Insert with Preview dialog box.

The Items list displays a list of items that may be inserted or substituted. The XML Tree Preview list shows the selected item and any of its mandatory children (in black), in the context of the XML tree (in gray); you can think of it as a preview of how the document will look after the change. If any elements will need to be deleted in the process, they display red and struck-through. Click OK to complete the insertion or replacement, or Cancel to abort it.

Some elements have mandatory children. If you insert such an element, its mandatory children must also be inserted. Clicking an element's (Mac OS) or (Windows) icon displays any child elements that must also be inserted along with that element. Clicking this icon does not display any optional children an element might have.

If an inserted element requires one of a list of non-optional elements (for example, (a | b | c)), avenue.quark uses the first element in the list (here, a). If the element requires one of a list of elements, and one or more of those elements is optional (for example, (a | b | c?)), avenue.quark leaves the element empty.

If the element you want is unavailable, it means the DTD does not permit new elements of that type to be inserted in this position.

What is a PCDATA block? A PCDATA block is an avenue.quark construction that lets you divide the text in an element into separate parts. PCDATA blocks are visible only in avenue.quark; in the exported XML, consecutive PCDATA blocks are merged.

To delete an element, comment, PCDATA block, or processing instruction:

1. In the XML Workspace palette, select the item you want to delete in the XML Tree list.

2. Control+click (Mac OS) or right+click (Windows) the item to display the XML Tree pop-up menu, and then choose Delete. The Delete dialog box is displayed.

Delete dialog box.

If the Delete menu item is unavailable, it means the DTD does not permit the deletion of the element you've selected.

The Items list displays the item being deleted. The XML Tree Preview list shows what the XML tree will look like after the deletion; items that will be deleted are indicated by red and strike thru.

3. Click OK to complete the deletion, or Cancel to abort it.

When you use avenue.quark to tag content, you must use a DTD; see "Working With DTDs" in Chapter 1, "Avenue.quark Basics". Tagging text is the process of associating that text with element types in the appropriate DTD.

There are several ways to tag text in avenue.quark. You can tag text manually, automate tagging with a tagging rule set, or enter content manually.

Use manual text tagging when you want precise control over exactly which text goes into which elements. To manually tag text from the active QuarkXPress document and copy it into the active XML document:

1. Scroll through the QuarkXPress document to the page containing the text you want to tag, and then select that text using the Content tool E.

2. In the XML Workspace palette, scroll through the XML Tree list until you can see the element or attribute with which you want to tag the selected text. (If you need to create that element or attribute, see "Working with XML Document Content" in this chapter.)

Only attributes specified as CDATA attributes may be used to tag text. Fixed and empty attributes cannot be used to tag text.

3. Click and drag the selected text to the element or attribute name in the XML Tree list. The text is copied into the element or attribute.

If the element or attribute already contains text, the text will be replaced.

4. To verify that the content has been properly tagged, select the element in the XML Tree list; the text contained by the element or attribute is displayed in the Content field.

If you drag text to a NMTOKENS or IDREFS attribute, spaces in that text will be interpreted as delimiters between items in a list of NMTOKENs or IDREFs.

Rule-based tagging lets you automate part of the process of tagging text and pictures. To make use of rule-based tagging, you create a tagging rule set (see Chapter 5, "Tagging Rule Sets"), then use that tagging rule set to automate part of the tagging process.

To use rule-based tagging to tag text from the active QuarkXPress document into the active XML document:

1. In the XML Workspace palette, choose a tagging rule set from the Tagging Rule Set pop-up menu.

2. Scroll through the XML Tree list until you can see the element where you want to begin rule-based tagging. For rule-based tagging to work, there must be at least one rule for this element or its children in the selected tagging rule set.

3. Select a range of text using the Content tool E or a text box using the Item tool e.

4. Press Command (Mac OS) or Ctrl (Windows), then click and drag the selected text or text box to the element name in the XML Tree list. The text is copied into the XML document according to the rules in the selected tagging rule set. Avenue.quark adds new elements to the XML document as necessary to accommodate the tagged content. If an ambiguous tagging situation arises, avenue.quark displays a dialog box, asking you what you want to do.

5. To verify that the content has been properly tagged, select each element in the XML Tree list; the text contained by the element is displayed in the Content field.

6. To verify that avenue.quark has tagged all the text you want it to tag, choose Show Tagged Content from the Utilities menu. Tagged and untagged text and pictures display with the colors indicated in the avenue.quark Preferences dialog box (Edit > Preferences > avenue.quark).

The Show Tagged Content command works only in QuarkXPress 4.1 or later.

Once you have tagged text in a QuarkXPress document, you can edit that text in the QuarkXPress document and it will automatically be updated in the XML Workspace palette. If the XML document is not open at the time, the text is updated the next time both documents are open.

Automatic content updating works only with elements; not with attributes.

If you want to break the link between a QuarkXPress document and an element in the active QuarkXPress document, select the element or attribute in the XML Tree list and then click the Break Dynamic Link button.

The Break Dynamic Link button lets you sever the link between the element selected in the XML Tree list and the QuarkXPress document from which it came.

To tag pictures from the active QuarkXPress document and copy their file names into the active XML document:

1. Scroll through the QuarkXPress document to the page containing the picture you want to tag, and then select its picture box.

2. In the XML Workspace palette, scroll through the XML Tree list until you can see the element or attribute with which you want to tag the selected picture. (If you need to create that element or attribute, see "Working with XML Document Content" in this chapter.)

Only attributes specified as CDATA attributes may be used to tag pictures. Fixed and empty attributes cannot be used to tag pictures.

3. Press Command (Mac OS) or Ctrl (Windows) and then click and drag the selected picture to the element or attribute name in the XML Tree list. The name of the picture is copied into the selected element or attribute.

If the target element or attribute already contains a name, the new name always replaces the old one.

In addition to copying content from a QuarkXPress document, avenue.quark lets you add additional content by entering it directly into the XML document. To add new content to an empty element, attribute, or comment in the active XML document:

1. In the XML Tree list, select the element, attribute, or comment to which you want to add content. (If you need to create it, see "Working with XML Document Content" in this chapter.)

Attributes may contain manually-entered content only if they are specified as CDATA attributes. Fixed and empty attributes cannot contain manually entered content.

2. Enter the content in the Content field.

You can also paste content from the clipboard into the Content field. Note that such text will lose any formatting it might have, and will be pasted as plain ASCII text.

3. To indicate that you're finished editing the selected element, press the Tab key.

You can manually add content only to elements that do not contain content from a QuarkXPress document. If an element contains content from a QuarkXPress document, edit that content in the QuarkXPress document; the copy of it in the XML document will be updated automatically.

Once your content has been tagged, you can preview how it will look when saved as XML. To preview the XML document displayed in the active XML Workspace palette, click the Preview XML button. The Preview XML dialog box is displayed.

The Preview XML button.

The Preview XML dialog box lets you preview the XML that will be created when you save the active XML document.

You can copy text from the Preview XML dialog box, but you cannot edit or delete it.

Although upper-ASCII characters (characters above ASCII 127) display unaltered in the Preview XML dialog box, such characters are converted to the appropriate codes at export depending on the encoding method you choose in the Save As dialog box.